Import Tezos X doc - #436

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-etherlink	Ready	Preview	Aug 7, 2026 12:07pm

Validation of the fix pass

Thanks @NicNomadic — this is a very thorough pass, and the commit-per-item structure made it easy to verify. I re-checked the fixes against the files (not just the commit messages) and rebuilt the site locally: 24 of the 26 items are fixed, and fixed correctly.

Verified in particular: the KT1 alias formula now matches the kernel exactly; the fee constants (135M / 9.9e-10) with the example correctly recomputed (270M backlog → 1.14 gwei checks out) and the table rebased; the DA fee now counts access-list bytes and includes the EIP-7702 term; callMichelsonView documented with a signature and the encoding guidance with the inline nat example + solidity_examples/ link is exactly what was missing; the icon map by label, the de-collapsed Overview, the homepage → Get started link, the Previewnet reframing, and the :::caution treatment of the WIP pages are all the right fixes. Local npm run build succeeds (remaining warnings are pre-existing on main).

Two remaining items:

1. Five moved pages fall outside the createRedirects prefix map — verified in the build output (build/<old-path>/index.html is not generated for them):

   • /get-started/chatbot → /overview/chatbot
   • /building-on-etherlink/sandbox → /testing/sandbox
   • /building-on-etherlink/testnet → /testing/testnet
   • /network/migrating-testnet → /testing/migrating-testnet
   • /network/fees → /evm/developing/fees (page deleted, redirect to its replacement)

   The plugin accepts an explicit redirects: [{from, to}, …] array alongside createRedirects — five entries would close this.

2. One stale cross-reference from the reorder: docs/overview/accounts-and-aliases.md:22 still says the tez is forwarded "via the gateway, as described below" — after the Overview reorder the gateway is now described in the previous page, not below. Suggest "(see Native Atomic Composability)".

Non-blocking, tracked: the <!--TX--> markers question (still open above), the "Etherlink EVM" → "EVM interface" sweep on inherited pages (41 files), and two stray "Native Atomic Calls" (testing/testnet.mdx:45, michelson/bridging.md) vs the full "Native Atomic Composability" name.

With the five redirect lines and the one-line cross-reference fix, this looks good to me.

A few more small items from one last read-through, this time from a beginner's seat (someone who copy-pastes tutorials and leans on an AI assistant):

1. docs/tutorials/index.md under-sells the content that exists: it lists only the cross-interface counter and says "More tutorials are on the way" — but the Prediction Market tutorial (3 parts, and actually the friendlier starting point for a pure-EVM beginner) is right there in the sidebar. Listing it on the index page is a 2-minute fix that changes the first impression from "this is sparse" to "there's a real path here".

2. Glossary: the base Tezos vocabulary is missing. The glossary covers the architecture terms well (Alias, Blueprint, Gateway, Sequencer…) but not the words an EVM-background reader actually stumbles on in the Michelson pages: Michelson itself (only "Michelson runtime" is defined), entrypoint, origination/originate (vs "deploy"), mutez. The KT1 explanation that exists in nac-counter.md:127 is exactly the right kind of one-liner — the glossary needs the same for these four.

3. Open question / suggestion: more and more readers will consume these docs through an AI assistant (pasting pages, or the assistant fetching them). Would it be worth adding an llms.txt / llms-full.txt? The docs are actually well-suited to it already — the network-information tables and nac-usage.md are self-contained — and Docusaurus has plugins that generate it at build time. Not a blocker, genuinely a question for the docs roadmap.

(Tiny nit while I'm here: the live-example links in nac-counter.md point to http://tzx-counter.vercel.app — plain HTTP triggers a browser warning; https:// works.)

Read-through: a Michelson developer trying to call an existing EVM contract

One more persona pass, this time on the direction the docs cover least. Not blocking this PR — this is the concrete scope for the "NAC reference layer" follow-up already tracked in the action plan — but the journey is worth reading in full, because it shows where a real reader stops.

The persona: a competent Tezos developer — 4 years of SmartPy, FA2 contracts in production, fluent with Taquito and octez-client, but zero Solidity and no idea what ABI encoding or a function selector is. The goal: a loyalty-points contract in SmartPy that, via NAC, (a) transfers USDC (an existing ERC-20 on the EVM side) to a user, (b) reads a USDC balance first, (c) handles a failed transfer cleanly.

The journey

1. They open the obvious page, michelson/nac-usage.md, and hit line 19: "Call an EVM contract by providing … the destination address, entrypoint selector, and ABI-encoded data." Neither "entrypoint selector" nor "ABI-encoded" is defined or linked anywhere (both are absent from the glossary), no Michelson types are given for the parameters, and there is no code example — in either Michelson or SmartPy — on the entire page. Compare evm/nac-usage.md:30-43, which gives the opposite direction a full Solidity interface plus a concrete call. The asymmetry is exactly backwards relative to need: the Solidity dev already knows ABI encoding; the Michelson dev is the one who needs the worked example.
2. They spot the ERC-20 wrapper (michelson/nac-usage.md:24-30, KT18oDJ…KvCChb) — which sounds like exactly the escape hatch they need. But the page lists no entrypoint signatures, no parameter types, no example call, and doesn't say whether the wrapper takes the target token address as a parameter (usable for any ERC-20, including USDC) or is bound to a fixed token. They literally cannot use it from what's written.
3. They look for the USDC address. It exists — evm/developing/tokens.mdx:38 — but that page is never linked from michelson/nac-usage.md or the NAC overview; our reader only found it by grepping. A Michelson dev following the docs' own navigation doesn't think to look under EVM → Developing.
4. They want to read the balance before transferring, so they look for the Michelson→EVM equivalent of callMichelsonView (evm/nac-usage.md:62-91). There is none, anywhere — and the docs don't say whether that's because it doesn't exist yet or because it's just undocumented. Silence reads as a docs gap; if the feature doesn't exist, saying so explicitly (with the workaround, e.g. an off-chain relayer doing eth_call) would actually be the better page.
5. They ask "what happens to my contract if the EVM transfer reverts?" The answer exists — overview/resources.md:38-39 (whole operation group reverts, standard Michelson semantics) — but not on the NAC usage page, and nothing links the two. Same for gas: the conversion is automatic (overview/resources.md:34-40), consistent with call_evm taking no gas parameter, but the reader has to cross-reference two pages to conclude that. The callback pattern with_result is named (michelson/nac-usage.md:36) with no signature and no example of the callback entrypoint a contract must implement.
6. They fall back to the tutorial — and discover tutorials/nac-counter.md only wires the EVM→Michelson direction (michelson/getting-started.md:26-28 says as much). examples/potluck-game.md is also EVM→Michelson (via an off-chain relayer). There is no worked example of a Michelson contract initiating a NAC call in the whole doc set.

Where they end up: they know the mechanism exists (call_evm, the wrapper, with_result) but cannot write a single line of it without guessing or asking a Solidity colleague. A recurring pattern: much of the information exists but was written from the EVM context and is never linked from the Michelson entry point — gas, alias formula, token addresses are all findable only if you already know to look on the other side.

Suggested scope for the follow-up issue

1. Rewrite michelson/nac-usage.md to mirror evm/nac-usage.md: exact call_evm signature with Michelson types (parameter/type table), one complete SmartPy example calling an arbitrary ERC-20, direct links to overview/resources.md (gas/failure semantics) and to the token-address table.
2. Document the ERC-20 wrapper properly: entrypoint signatures, whether it's parameterized by token address, one example against an already-deployed token, failure behavior.
3. A "read-only calls from Michelson" section: either the view mechanism if it exists, or an explicit "not currently possible — here is the workaround" note. (Question for the kernel team: does a Michelson→EVM view exist, and is the wrapper token-parameterized? The docs should state whichever is true.)
4. Specify with_result: the callback entrypoint's exact parameter type, a SmartPy example, and the no-callback failure behavior stated on this page (not only in resources.md).
5. A mirror tutorial (Michelson contract initiating a NAC call to an ERC-20 on Previewnet), with success verified on both sides (Michelson storage + Blockscout).
6. Glossary: add ABI encoding and function selector.

Happy to open this as a tracked issue with the above as the description.

In response to thread #436 (comment):

• I added the five redirect lines and fixed the one-line cross-reference (commits 93236e6 and d233dcc, respectively).
• I also confirm that I introduced the HTML-comment tags (e.g., <!--TX-->) to later revert the un-branding of Tezos X, so they should stay in the production version until the sunset of the brand "Etherlink".

In response to thread #436 (comment):

1. added commit better sell section Tutorials
2. added commit add a few Michelson terms to the glossary
3. created issue Add files llms(-full).txt #438
   Also I fixed the URL of tzx-counter.

In response to thread #436 (comment) I created issue #439